/*

   **********************************************************************
   *                                                                    *
   * This file contains the code for an image object for a content-     *
   * based image retrieval application that "summarizes" an image and   *
   * sends the resulting image "signature" to a server for              *
   * classification. The server returns the classification result in    *
   * the form of a Web page containing example images of the input      *
   * image's category.                                                  *
   *                                                                    *
   * The image class defined here is rather specific to this particular *
   * application and is not really designed for broad reuse (just yet). *
   *                                                                    *
   **********************************************************************
*/

/*
   **********************************************************************
   *                                                                    *
   * Gist   -- content-based image retrieval application for the gPhone *
   *                                                                    *
   * Copyright (C) 2011 Yong Zeng                                       *
   *                                                                    *
   * This file is part of Gist.                                       *
   *                                                                    *
   * Gist is free software; you can redistribute it and/or modify it  *
   * under the terms of the GNU General Public License as published by  *
   * the Free Software Foundation; either version 2 of the License, or  *
   * (at your option) any later version.                                *
   *                                                                    *
   * Gist is distributed in the hope that it will be useful, but      *
   * WITHOUT ANY WARRANTY; without even the implied warranty of         *
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU   *
   * General Public License for more details.                           *
   *                                                                    *
   * You should have received a copy of the GNU General Public License  *
   * along with Goggle; if not, write to the Free Software Foundation,  *
   * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.       *
   *                                                                    *
   **********************************************************************
*/

//----------------------- PACKAGE SPECIFICATION -------------------------

package vision.gistcomputing ;

//------------------------------ IMPORTS --------------------------------

// Android utilities
import android.util.Log ;

//------------------------- CLASS DEFINITION ----------------------------

/**
   This is a utility class for encapsulating the SIFT descriptors as
   required by the Goggle content-based image retrieval application.
*/
class SiftDescriptor {

/// Essentially, a SIFT descriptor is a collection of histograms that
/// count orientations at different scales. The size of the descriptor
/// would thus be based on the number of scales and orientations.
/// However, the "canonical" number of bins (as per David Lowe's 2004
/// SIFT paper) is 4x4x8 = 128 (4 bins along x, 4 along y and 8
/// orientations).
public static final int SIZE = 128 ;

/// The descriptor contents are just numbers in the range 0-255, which
/// means that we can represent the descriptor with an array of bytes.
///
/// DEVNOTE: Unfortunately, Java doesn't support unsigned bytes. This
/// means that descriptor values exceeding 128 will show up as negative
/// numbers. Since negative numbers are represented in 2's complement
/// form, we could convert negative descriptor values to the equivalent
/// numbers in the 129-255 range. However, that would simply complicate
/// the code with some unnecessary bit fiddling type operations. Much
/// simpler to use ints and ensure that they are in 0-255 range.
private int[] m_values ;

//-------------------------- INITIALIZATION -----------------------------

/// To create a SIFT descriptor object, we need an array containing the
/// descriptor values.
public SiftDescriptor(int[] values)
{
   m_values = new int[SIZE] ;
   System.arraycopy(values, 0, m_values, 0, SIZE) ;
}

//----------------------------- ACCESSORS -------------------------------

/// Return the descriptor value corresponding to the given index.
public int get(int index)
{
   return m_values[index] ;
}

//--------------------------- DEBUG SUPPORT -----------------------------

/// Dump the first couple of bytes in a descriptor.
public void dump()
{
   StringBuffer s = new StringBuffer() ;
   for (int i = 0; i < 10; ++i)
      s.append(m_values[i] + " ") ;
   Log.e("Goggle", s.toString()) ;
}

/// Convert a descriptor to a human-readable string.
public String toString()
{
   StringBuffer s = new StringBuffer(SIZE << 2) ;
   for (int i = 0; i < SIZE; ++i)
      s.append(m_values[i] + " ") ;
   return s.toString() ;
}

//-----------------------------------------------------------------------

} 
